Spending functions: 4.0: Spending function overview

Description

Spending functions are used to set boundaries for group sequential designs. Using the spending function approach to design offers a natural way to provide interim testing boundaries when unplanned interim analyses are added or when the timing of an interim analysis changes. Many standard and investigational spending functions are provided in the gsDesign package. These offer a great deal of flexibility in setting up stopping boundaries for a design.

Usage

spendingFunction(alpha, t, param)

Arguments

alpha

Real value $> 0$ and no more than 1. Defaults in calls to gsDesign() are alpha=0.025 for one-sided Type I error specification and alpha=0.1 for Type II error specification. However, this could be set to 1 if

A vector of points with increasing values from 0 to 1, inclusive. Values of the proportion of sample size/information for which the spending function will be computed.

param

A single real value or a vector of real values specifying the spending function parameter(s); this must be appropriately matched to the spending function specified.

Value

An object of type spendfn.
nameA character string with the name of the spending function.
paramany parameters used for the spending function.
parnamea character string or strings with the name(s) of the parameter(s) in param.
sfthe spending function specified.
spenda vector of cumulative spending values corresponding to the input values in t.
boundthis is null when returned from the spending function, but is set in gsDesign() if the spending function is called from there. Contains z-values for bounds of a design.
probthis is null when returned from the spending function, but is set in gsDesign() if the spending function is called from there. Contains probabilities of boundary crossing at i-th analysis for j-th theta value input to gsDesign() in prob[i,j].

Details

Spending functions have three arguments as noted above and return an object of type spendfn. Normally a spending function will be passed to gsDesign() in the parameter sfu for the upper bound and sfl for the lower bound to specify a spending function family for a design. In this case, the user does not need to know the calling sequence - only how to specify the parameter(s) for the spending function. The calling sequence is useful when the user wishes to plot a spending function as demonstrated below in examples. In addition to using supplied spending functions, a user can write code for a spending function. See examples.

References

Jennison C and Turnbull BW (2000), Group Sequential Methods with Applications to Clinical Trials. Boca Raton: Chapman and Hall.

Examples

Run this code

# Example 1: simple example showing what mose users need to know

# design a 4-analysis trial using a Hwang-Shih-DeCani spending function 
# for both lower and upper bounds 
x <- gsDesign(k=4, sfu=sfHSD, sfupar=-2, sfl=sfHSD, sflpar=1)

# print the design
x

# plot the alpha- and beta-spending functions
plot(x, plottype=5)

# Example 2: advance example: writing a new spending function  
# Most users may ignore this!

# implementation of 2-parameter version of
# beta distribution spending function
# assumes t and alpha are appropriately specified (does not check!) 
sfbdist <- function(alpha,  t,  param)
{  
   # check inputs
   checkVector(param, "numeric", c(0, Inf), c(FALSE, TRUE))
   if (length(param) !=2) stop(
   "b-dist example spending function parameter must be of length 2")

   # set spending using cumulative beta distribution and return
   x <- list(name="B-dist example", param=param, parname=c("a", "b"), 
             sf=sfbdist, spend=alpha * 
           pbeta(t, param[1], param[2]), bound=NULL, prob=NULL)  
           
   class(x) <- "spendfn"
   
   x
}

# now try it out!
# plot some example beta (lower bound) spending functions using 
# the beta distribution spending function 
t <- 0:100/100
plot(t, sfbdist(1, t, c(2, 1))$spend, type="l", 
    xlab="Proportion of information", 
    ylab="Cumulative proportion of total spending", 
    main="Beta distribution Spending Function Example")
lines(t, sfbdist(1, t, c(6, 4))$spend, lty=2)
lines(t, sfbdist(1, t, c(.5, .5))$spend, lty=3)
lines(t, sfbdist(1, t, c(.6, 2))$spend, lty=4)
legend(x=c(.65, 1), y=1 * c(0, .25), lty=1:4, 
    legend=c("a=2, b=1","a=6, b=4","a=0.5, b=0.5","a=0.6, b=2"))

Run the code above in your browser using DataLab

Get 50% off unlimited learning